<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
 <head>
  <meta http-equiv="content-type" content="text/html; charset=UTF-8">
  <title>Extension globals</title>

 </head>
 <body><div class="manualnavbar" style="text-align: center;">
 <div class="prev" style="text-align: left; float: left;"><a href="internals2.structure.modstruct.html">The zend_module structure</a></div>
 <div class="next" style="text-align: right; float: right;"><a href="internals2.structure.lifecycle.html">Life cycle of an extension</a></div>
 <div class="up"><a href="internals2.structure.html">扩展的结构</a></div>
 <div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="internals2.structure.globals" class="sect1">
  <h2 class="title">Extension globals</h2>

  <div class="sect2" id="internals2.structure.globals.intro">
   <h3 class="title">Introduction to globals in a PHP extension</h3>

   <p class="simpara">
    In a language such as C, a &quot;global&quot; variable is a variable that can be
    accessed from any function without any extra declaration. These traditional
    globals have a few drawbacks:
   </p>

   <ul class="itemizedlist">

    <li class="listitem">
     <span class="simpara">
      Barring any special options passed to the compiler, a global variable can
      be accessed and changed by any piece of code anywhere in the program,
      whether or not that code should be doing so.
     </span>
    </li>

    <li class="listitem">
     <span class="simpara">
      A typical global variable is not thread safe.
     </span>
    </li>

    <li class="listitem">
     <span class="simpara">
      The names of global variables are as global as the variables themselves.
     </span>
    </li>

   </ul>

   <p class="simpara">
    A PHP extension&#039;s globals are more properly called the &quot;extension state&quot;,
    since most modules must remember what they&#039;re doing between function calls.
    The &quot;counter&quot; extension is a perfect example of this need: The basic
    interface calls for a counter with a persistent value. A programmer new to
    Zend and PHP might do something like this in <var class="filename">counter.c</var>
    to store that value:
   </p>

   <div class="example" id="internals2.structure.globals.intro.wrong-way">
    <p><strong>Example #1 The wrong way to store the basic counter interface&#039;s value</strong></p>
    <div class="example-contents">
<div class="ccode"><pre class="ccode">/* ... */
static long basic_counter_value;

/* ... */

PHP_FUNCTION(counter_get)
{
    RETURN_LONG(basic_counter_value);
}</pre>
</div>
    </div>

   </div>

   <p class="simpara">
    On the surface this appears a viable solution, and indeed in a simple test
    it would function correctly. However, there are a number of situations in
    which more than one copy of PHP is running in the same thread, which means
    more than one instance of the counter module. Suddenly these multiple
    threads are sharing the same counter value, which is clearly undesirable.
    Another problem shows itself when considering that another extension might
    someday happen to have a global with the same name, and due to the rules of
    C scoping, this has the potential to cause a compile failure, or worse, a
    runtime error. Something more elaborate is needed, and so exists Zend&#039;s
    support for thread-safe per-module globals.
   </p>

  </div>

  <div class="sect2" id="internals2.structure.globals.declaring">
   <h3 class="title">Declaring module globals</h3>
   
   <p class="simpara">
    Whether a module uses only a single global or dozens, they must be defined
    in a structure, and that structure must be declared. There are some macros
    that assist with doing so in a way that avoids name conflicts between
    modules: <span class="function"><strong>ZEND_BEGIN_MODULE_GLOBALS()</strong></span>,
    <span class="function"><strong>ZEND_END_MODULE_GLOBALS()</strong></span>, and
    <span class="function"><strong>ZEND_DECLARE_MODULE_GLOBALS()</strong></span>. All three take as a
    parameter the short name of the module, which in the case of the counter
    module is simply <em>&quot;counter&quot;</em>. Here is the global structure
    declaration from <var class="filename">php_counter.h</var>:
   </p>

   <div class="example" id="internals2.structure.globals.declaring.doth">
    <p><strong>Example #2 The counter module&#039;s globals</strong></p>
    <div class="example-contents">
<div class="ccode"><pre class="ccode">ZEND_BEGIN_MODULE_GLOBALS(counter)
    long        basic_counter_value;
ZEND_END_MODULE_GLOBALS(counter)</pre>
</div>
    </div>

   </div>

   <p class="simpara">
    And this is the declaration from <var class="filename">counter.c</var>:
   </p>

   <div class="example" id="internals2.structure.globals.declaring.dotc">
    <p><strong>Example #3 The counter module&#039;s global structure declaration</strong></p>
    <div class="example-contents">
<div class="ccode"><pre class="ccode">ZEND_DECLARE_MODULE_GLOBALS(counter)</pre>
</div>
    </div>

   </div>
  
  </div>
  
  <div class="sect2" id="internals2.structure.globals.using">
   <h3 class="title">Accessing module globals</h3>
   
   <p class="simpara">
    As discussed above, per-module globals are declared inside a C structure
    whose name is obscured by Zend macros. As a result, the ideal way to access
    members of this structure is by the use of further macros. Accordingly, most
    if not all extensions which have globals have a declaration like this
    somewhere in their header file:
   </p>

   <div class="example" id="internals2.structure.globals.using.accessor">
    <p><strong>Example #4 Accessor macros for per-module globals</strong></p>
    <div class="example-contents">
<div class="ccode"><pre class="ccode">#ifdef ZTS
#define COUNTER_G(v) TSRMG(counter_globals_id, zend_counter_globals *, v)
#else
#define COUNTER_G(v) (counter_globals.v)
#endif</pre>
</div>
    </div>

   </div>

   <blockquote class="note"><p><strong class="note">Note</strong>: 
    <span class="simpara">
     This could have been generalized into a macro of its own by the Zend API,
     but as of PHP 5.3 (and PHP 6 at the time of this writing), that hasn&#039;t
     happened. The global accessor construct is written into the header by
     <strong class="command">ext_skel</strong> and thus is generally left alone by extension
     writers, unless they wish to change the name of the accessor macro.
    </span>
   </p></blockquote>

   <blockquote class="note"><p><strong class="note">Note</strong>: 
    <span class="simpara">
     <strong><code>COUNTER_G</code></strong> was the name given to the macro by
     <strong class="command">ext_skel</strong>, but it&#039;s not necessary for it to have that
     name and could just as easily be called <em>FOO</em> instead.
    </span>
   </p></blockquote>

   <p class="simpara">
    Any code in the counter extension that accesses a global must thus wrap it
    in the macro <strong><code>COUNTER_G</code></strong>.
   </p>

   <div class="warning"><strong class="warning">Warning</strong>
    <p class="simpara">
     Any function which accesses globals must either be declared by Zend macros,
     have <strong><code>TSRMLS_DC</code></strong> as its last argument, or call the macro
     <strong><code>TSRMLS_FETCH</code></strong> before accessing the globals. See
     the TSRM documentation for
     more information.
    </p>
   </div>

   <p class="simpara">
    So with all of that in mind, here is our new version of the
    <span class="function"><a href="internals2.counter.function.counter-get.html" class="function">counter_get()</a></span>:
   </p>
  
   <div class="example" id="internals2.structure.globals.intro.right-way">
    <p><strong>Example #5 The right way to store the basic counter interface&#039;s value</strong></p>
    <div class="example-contents">
<div class="ccode"><pre class="ccode">/* php_counter.h */
ZEND_BEGIN_MODULE_GLOBALS(counter)
    long        basic_counter_value;
ZEND_END_MODULE_GLOBALS(counter)

#ifdef ZTS
#define COUNTER_G(v) TSRMG(counter_globals_id, zend_counter_globals *, v)
#else
#define COUNTER_G(v) (counter_globals.v)
#endif

/* counter.c */
ZEND_DECLARE_MODULE_GLOBALS(counter)

/* ... */

PHP_FUNCTION(counter_get)
{
    RETURN_LONG(COUNTER_G(basic_counter_value));
}</pre>
</div>
    </div>

   </div>

   <p class="simpara">
    This is a correct implementation. It is not, however, a complete one. The
    section <a href="internals2.structure.lifecycle.html" class="xref">Life cycle of an extension</a> explains why.
   </p>
  
  </div>

 </div><hr /><div class="manualnavbar" style="text-align: center;">
 <div class="prev" style="text-align: left; float: left;"><a href="internals2.structure.modstruct.html">The zend_module structure</a></div>
 <div class="next" style="text-align: right; float: right;"><a href="internals2.structure.lifecycle.html">Life cycle of an extension</a></div>
 <div class="up"><a href="internals2.structure.html">扩展的结构</a></div>
 <div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
